home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / storage.zip / STORAGE.DOC < prev    next >
Text File  |  1991-02-09  |  11KB  |  215 lines
  1.  
  2.  
  3.                               STORAGE.PAS
  4.  
  5.                                   By
  6.  
  7.                             Marcos R. Della
  8.  
  9.  
  10.  
  11.      This Unit was designed to allow you the user to save and restore
  12.      several bodies of text or information into a single file and restore
  13.      that information based on a single LONGINT.  Examples of usage are:
  14.  
  15.         In a BBS system where you are creating a message base and need to
  16.         save several messages however do not want to create several files.
  17.         You also want the messages compressed to save disk space
  18.  
  19.         In a program where you are storing variable length records that you
  20.         want to keep track of in an indexed database.  Your index key can
  21.         use the LONGINT returned by the storage system as your reference
  22.         into the record.  The record will be stored in compressed format.
  23.  
  24.      I'm sure that people can think of all kinds of neat things to do with
  25.      this system.  The main advantage that you have with this object is
  26.      that ANY kind of data can be stored {Length: 0 < sizeof(data) < 65530}
  27.      as long as it fits in the buffer space.
  28.  
  29.   BRIEF DESCRIPTION:
  30.   ------------------
  31.  
  32.      The way it is supposed to work is that you either create or open a
  33.      previously created file.  You can define how big you want your
  34.      read/write buffer for the file and how you want to open it (read,
  35.      write, or read/write).  Once open, your basic functions consist of
  36.      "writing" messages or "reading" messages.
  37.  
  38.      To write a message, you create your own buffer of any size from 1 to
  39.      65530 bytes in length.  Note that the system will write out everything
  40.      in that block that you assign including wasted space, pointers,
  41.      whatever.  If you would like to store a series of strings, you could
  42.      possibly do the following:
  43.  
  44.               TYPE  str_buffer = ARRAY[1..128] OF STRING;
  45.               VAR   mybuff : str_buffer;
  46.  
  47.      This would create a block of memory that is 128 * 256 bytes long.  The
  48.      only problem here is that all wasted memory will also be stored if you
  49.      select it that way.  Doing a little pre-buffering is a prefered method.
  50.  
  51.      To write your information, you simply call the write routine with the
  52.      location of your buffer and how many bytes to write out.  The system
  53.      will return a LONGINT that is your KEY to retrieving the information
  54.      at a later date.
  55.  
  56.               keyvalue := TStorage.WriteMsg(SIZEOF(mybuff),mybuff);
  57.  
  58.      To later read the information back, the storage system will grab a
  59.      block of memory equal to the original size, and return to you a
  60.      pointer to that block...
  61.  
  62.               bytesread := TStorage.ReadMsg(keyvalue,mybufptr);
  63.               mybuff := str_buffer(mybufptr^);
  64.  
  65.      The information is automatically stored in compressed format on the
  66.      disk so you don't have to worry about all that.  Thats about all there
  67.      is to the whole thing!  There are other routines included to do
  68.      various other things, but you now have the basics!
  69.  
  70.  
  71.  
  72.   OBJECT DESCRIBED:
  73.   -----------------
  74.  
  75.      Note that the information both stored and retrived are limited to 65530
  76.      characters in length.  In the current version, this will require you to
  77.      have somewhere on your heap that much space. In the future this routine
  78.      will be made EMS aware so that it will grab the best option for heap
  79.      storage and manipulation out there...
  80.  
  81.      The OBJECT TStorage is a Child of the BufStream Object.  This means that
  82.      it still retains all the lower level stuff from BufStream, DOSStream, and
  83.      TStream if you have some sort of use for that.
  84.  
  85.      The routines provided are as follows:
  86.  
  87.  
  88.   TStorage.Init(FNameStr, Mode, BufSize)
  89.       This routine will initialize the file that you are going to be reading
  90.       from or writing to.  You can use the stCreate, stOpenWrite, stOpenRead,
  91.       or stOpen as your mode.  If you use the stCreate, the system will write
  92.       over your previous file.  If you use stOpenWrite, you can ONLY write
  93.       to the file, you cannot do reads and visa-versa with stOpenRead.  If
  94.       you use stOpen, then you can do both operations at the same time.
  95.  
  96.       This is another item that in the future will be changed to do record
  97.       locking of the specified section you are writing to so that other
  98.       users on a network can read from the various other parts of the file.
  99.  
  100.       The BufSize defines the internal buffer size that the system will use
  101.       to buffer your I/O reads.  Borland recommends around 1024 for standard
  102.       usage.  You might make it bigger or smaller depending on your needs.
  103.  
  104.   TStorage.WriteMsg(NumBytes : WORD; Buf) : LONGINT
  105.       This takes a buffer that you define and will write out NumBytes of
  106.       continuous memory out to the disk.  While writing the information
  107.       out, it is running it through the inherited compression routine.
  108.       This will then return a LONGINT to the user as the reference point
  109.       for the information stored.
  110.  
  111.   TStorage.ReadMsg(INdex : LONGINT; VAR Buf : POINTER) : WORD
  112.       This is how you retrieve your text.  You pass the index that you got
  113.       earlier from TStorage.WriteMsg to this routine and it will pass you a
  114.       buffer pointer.  This points to the exact same stuff that was earlier
  115.       stored.  You can then overlay your TYPE onto the pointer to retrieve
  116.       specific information that you want.  NOTE:  If the index that you pass
  117.       is not the beginning of a stored pattern, the ReadBuf routine will
  118.       assume that you are reading a STANDARD text file and will rewind
  119.       and read the ENTIRE file into the buffer.  This is how you can use
  120.       the same routine to read normal text files as well as those created
  121.       by this Object.  If the message was deleted by the DeleteMsg routine,
  122.       you will get an errorlevel of 100 (Disk Read Error) returned to you
  123.       from the function.
  124.  
  125.   TStorage.DeleteMsg(Index)
  126.       This function does not actually delete the message out of the stream
  127.       as this would then mess up all subsequent index pointers.  Instead, it
  128.       changes the compression routine variable to $FF indicating that the
  129.       message is no longer valid.  To actually take the messages out of the
  130.       stream, you need to use the CleanUpMsg procedure.
  131.  
  132.   TStorage.CleanUpMsg
  133.       This procedure will scan the message stream, and re-write it out to a
  134.       seperate file leaving out all the deleted messages.  It then creates
  135.       a linked list of the old indexes and their new values.  This is then
  136.       used by you, the user, to change all your old saved index values.
  137.       NOTE:  Make sure that you do the index change BEFORE calling the
  138.       TStorage.Done routine as this will remove your list from memory and
  139.       all your pointers will be subsiquently screwed up.  If there is a
  140.       problem and you need to restore the previous file, you can rename
  141.       .$$$ file back to your filename.  The .$$$ file is not deleted until
  142.       the TStorage.Done is called.
  143.  
  144.   TStorage.NewIndex(Index) : LONGINT
  145.       When you call this routine with an old index number, it will return
  146.       to you the new index reference number. You'll get a -1 if the system
  147.       cannot fine an original index number.  To use this, you can scan
  148.       through your recorded indexes in your data file sequentially and call
  149.       this routine with each one you get.  Then replace the old value with
  150.       the new value.  If you get a -1 as your return, then the old message
  151.       was either originally deleted or lost to the system.  This will ALWAYS
  152.       return a -1 if you haven't made a VALID call to TStorage.CleanUpMsg.
  153.       It will also reset after a TStorage.Done has been executed.  Make sure
  154.       that you use this after the TStorage.CleanUpMsg routine if you want
  155.       to retain the changes made.
  156.  
  157.   TStorage.DeleteCleanUp
  158.       If you decide that for some reason something went wrong somewhere and
  159.       everything is screwed up, you can prevent TStorage.Done from replacing
  160.       your original msg file by calling this routine.  It will remove the
  161.       .$$$ file from the disk and clear out all TStorage.NewIndex references.
  162.  
  163.   TStorage.Compress(NumBytes : WORD; CompType : BYTE; VAR Buf) : WORD
  164.       This current compression routine uses the Splay tree system.  If you
  165.       want more information, see the bottom of this documentation.  This
  166.       will take "NumBytes" of information located in the "Buf" and then
  167.       compress them and store them to the TBufStream at the Current seeked
  168.       location.  Make sure that your pointer is at the correct place before
  169.       you call this routine.  It then returns exactly how many characters
  170.       were written out to the disk.
  171.  
  172.   TStorage.DeCompress(NumBytes : WORD; CompType : Byte; VAR Buf)
  173.       Same as the compression except that this goes backwards.  The NumBytes
  174.       defines how big the original text should have been. This is generally
  175.       retrieved from the header information.
  176.  
  177.   TStorage.InitCompress;
  178.       This is the routine that the compression routines will call prior to
  179.       actually compressing or decompressing the information.  This is so that
  180.       you can initialize any local variables or whatever you feel like for
  181.       the compression routines.
  182.  
  183.   TStorage.Done
  184.       Here is where you clean up all the messes, close all the files, and
  185.       return all the used heap back.  Remember to call this when your done
  186.       using the routines
  187.  
  188.   ERRORS Returned
  189.       When you check the TStorage.Status Integer, if you do not get an stOk
  190.       returned, then something went wrong.  To identify it from this Unit,
  191.       You can check TStorage.Status against stStoreError.  Errors also
  192.       included are stStoreReadErr, stStoreWriteErr, and stStoreUnknownErr.
  193.       These are stored in the TStorage.ErrorInfo location.
  194.  
  195.   ---------------------------------------------------------------------------
  196.  
  197.   These routines were originally designed as a message storage routine for a
  198.   new BBS system message base that we are putting together, however we have
  199.   used this storage format for a varity of purposes as you can store variable
  200.   length messages to one file and only have to keep track of an index.  It
  201.   also attempts to save on disk space which is ALWAYS at a premium around
  202.   here.
  203.  
  204.   If you have any suggestions or improvments on this file or its usage, or
  205.   would just like to chat, you can reach me at the following:
  206.  
  207.         Marcos R. Della
  208.         5084 Rincon Ave.
  209.         Santa Rosa, CA 95409
  210.  
  211.         CIS: 71675,765
  212.  
  213.   ---------------------------------------------------------------------------}
  214.  
  215.